<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
<title>Chordshop File Format Guide</title>
</head>
<body>
<center><h1>Chordshop File Format Guide</h1></center>
<hr/>
<h2><u>Introduction</u></h2>
<p>
Chordshop files use a modified ChordPro format.  The ChordPro format originated from a program
called "Chord" which used curly braces ({}) to
specify "directives", square brackets ([]) to call out chords, and hashes (#)
to specify comments.  For example:
</p>
<table border="0" bgcolor="#e8e8e8" width="100%" cellpadding="10"><tr><td><pre>
# This line is ignored
\{title:Amazing Grace}
[G]Amazing grace, [Bm]how [C]sweet the [G]sound
</pre></td></tr></table>
<p>
Chordshop supports a small subset of the original ChordPro directives,
and adds some of its own.  The one major difference between ChordPro and
Chordshop syntax is the addition of measure delimiters.  The pipe character,
sometimes called a bar, represents a measure bar.
</p>
<p>
I recommend saving Chordshop files with a ".csp" extension to distiguish them from normal
ChordPro files; however, this is not necessary.  ChordPro files have been seen with many extensions,
but the dominate one seems to be ".pro".  When I started converting my files into Chordshop format, I
called them Chordshop <tt>.pro</tt> files instead of normal <tt>.pro</tt> files, hence the ".csp" extension.
</p>
<hr/>
<h2><u>Comments</u></h2>
<p>
File comments start with a hash (#) and are totally ignored and not processed
in any way.  They do not show up in the generated chord sheet.
</p>
<hr/>
<h2><u>Chords</u></h2>
<p>
Anything between square brackets ([]) is assumed to be a chord, so don't use
square brackets for anything else in the file.
</p>
<hr/>
<h2><u>Directives</u></h2>
<p>
Directives must be on a line by themselves.  Anything after a directive is ignored.
Some directives take a value and some do not.  If a value is taken,
then the directive has a colon after the its name, and anything after the
colon is the value.
</p>
<h3><u>Basic Directives</u></h3>
<dl>
<dt>
{title:} or {t:}
</dt>
<dd>
<p>
    Specifies the title.  There should only be one
    title directive in the file.  The title is printed
    centered at the top of the first page.
</p>
</dd>
<dt>
{subtitle:} or {st:}
</dt>
<dd>
<p>
    Specifies a subtitle.  There can be multiple subtitle
    directives, and each one is printed directly below the
    title (or previous subtitle) in a smaller font.<br/>
   <br/>
    Only the first subtitle is included in the PDF outline.  It will look like this:
    "Song Title (Subtitle)".<br/>
   <br/>
    Note that Chordshop provides "credits" and "copyright" directives,
    so the subtitle can be dedicated to true subtitles. For instance, if there are sereral
    versions of a song, the subtitles might read "Easy Version" and "Correct Version".
    If there are two songs with the same name, but different composers, the subtitles
    might be "Smith" and "Jones".
</p>
</dd>
<dt>
{comment:} or {c:}
</dt>
<dd>
<p>
    Specifies a <strong>printed</strong> comment.  This is not an internal comment
    to be ignored, but rather a comment to be printed on the chord sheet
    in a different font that sets it apart as a comment.  This is generally
    a smaller italic font.
</p>
</dd>
</dl>
<h3><u>Block Delimiters</u></h3>
<p>
Blocks of lyrics/chords can be delimited by pairs of "start" and "end" directives.
The original ChordPro format supported "tab" and "chorus" blocks; Chordshop adopts some
extensions added by other programs, namely a "bridge" block and an arbitrarily
named block.  To use any of these, use a "start" directive, followed by chords and
lyrics, and then the "end" directive.
</p>
<dl>
<dt>
{start<sub>of</sub>chorus} or {soc} and {end<sub>of</sub>chorus} or {eoc}
</dt>
<dd>
<p>
    Delimits a chorus block.  This is set apart by labeling it "Chorus" and
    indenting the block so it is obviously a chorus.
</p>
</dd>
<dt>
{start<sub>of</sub>tab} or {sot} and {end<sub>of</sub>tab} or {eot}
</dt>
<dd>
<p>
    Delimits a tab block.  The text between these directives is not
    processed in anyway, but is just printed in a monospaced font.
    The block is also labeled "Tab".
</p>
</dd>
<dt>
{start<sub>of</sub>bridge} or {sob} and {end<sub>of</sub>bridge} or {eob}
</dt>
<dd>
<p>
    Delimits a bridge block.  This is set apart in the same manner
    as the chorus.
</p>
</dd>
<dt>
{start<sub>of</sub>block:} or {soblk:} and {end<sub>of</sub>block} or {eoblk}
</dt>
<dd>
<p>
    Delimits a named block.  This block is labeled, but not indented.
    This is useful for labeling verses.  A value needs to be given after
    the colon.  For example: {soblk:Verse 1}
</p>
</dd>
</dl>
<h3><u>Chordshop Specific Directives</u></h3>
<p>
These are directives that provide extra information about the songs or the
performance of them.  None of these are necessary, but if they are present,
they will usually be printed in the header.
</p>
<dl>
<dt>
{key:}
</dt>
<dd>
<p>
    The key is printed in the header for convenience and the PDF outline
    will say something like "Song Title (Subtitle) -&gt; in G".  If provided, the key directive
    also allows the user to transpose by named keys instead of a number of intervals.
</p>
</dd>
<dt>
{timing:}
</dt>
<dd>
<p>
    Specifies the meter of a song. Example usage: {timing:4/4} or {timing:3/4}. This
    is not displayed in the header, but rather before the next measure given in the file.  This
    allows for a change in meter, say from 4/4 to 2/4 or something similar, in the middle of a song.
</p>
</dd>
<dt>
{order:}
</dt>
<dd>
<p>
    This is for performance purposes and assumes that you have named all
    of the blocks.  Example usage: {order:V1,C,V2,B,C,C} or
    {order:Verse 1, Chorus, Verse 2, Chorus}.  This is simply printed in the header.
</p>
</dd>
<dt>
{credits:}
</dt>
<dd>
<p>
    This is the composer or author line.  This is prefered over using {subtitle:}.
</p>
</dd>
<dt>
{copyright:}
</dt>
<dd>
<p>
    This is the copyright information line.  This is prefered over using {subtitle:}.
</p>
</dd>
</dl>
<h3><u>Chord Definition Directives</u></h3>
<p>
Chords can be defined within a file to specify a particular fingering
for a certain chord.
</p>
<dl>
<dt>
{define:}
</dt>
<dd>
<p>
    Defines a chord fingering.  Examples:<br/>
    {define:G7 base-fret 1 frets 3 2 0 0 0 1}<br/>
    {define:Bm base-fret 1 frets x x 4 4 3 2}<br/>
    {define:Bm base-fret 2 frets x x 3 3 2 1}<br/>
    <br/>
    This could also be used to show different voicings of a chord in the same song:<br/>
    {define:G(I) base-fret 1 frets 3 2 0 0 0 3}<br/>
    {define:G(II) base-fret 1 frets 3 2 0 0 3 3}<br/>
    [G(I)]Words go here and [G(II)]here too.<br/>
</p>
</dd>
<dt>
{instrument:}
</dt>
<dd>
<p>
    Standard guitar is the default instrument.  This directive overrides the default.  The value
    should be one of the instrument specific chord definition files (*.cd) without the extension.
    This is only useful for files which contain a {define:} directive. Otherwise, there is no
    reason to hardcode the instrument into the file; just handle it from the SongBook file or a
    command-line switch.
</p>
</dd>
</dl>
<h3><u>Configuration Directive</u></h3>
<p>
The configuration of Chordshop output is done largely through a configuration file called "chordshop.cfg"
in the Chordshop program directory.  It is basically a text file with a bunch of variables set
to some value.  Any of these variables can be overriden in a particular song file by using the
set directive.
</p>
<dl>
<dt>
{set:}
</dt>
<dd>
<p>
    Any configuration variable can be overriden with this directive. The general form
    of usage is {set:variable=value}. Example usage: {set:fonts.chords_size=12}
</p>
</dd>
</dl>
<p>
See the <tt>chordshop.cfg</tt> file for the full list of variables.
</p>
<p>
Take special note that the {set:} directive can in turn be overriden in the Songbook file.
See the Chordshop User Guide's section on configuration for the order of precedence.
</p>
<p>
You may ask, why specify some information through new directives (like order, credits, key, etc.)
and then make the rest of the values mere configuration variables that must be changed through
the set directive?  The answer is simple.  Anything
relating <em>directly to the song or its performance</em> is a real directive, anything relating soley
to the appearance of the output is a configuration variable suitable for modification with {set:}.
The goal here is to separate the song content from the presentation of that content.  In other words,
keep the Chordshop specific functionality out of the directives.  This will
hopefully keep the "ChordPro Plus" format (A.K.A. the Chordshop format) neutral enough for use with
other programs.
</p>
<table border="1" bgcolor="#ffffee" width="80%" cellpadding="15">
<tr><td>
<p>
In general, I consider it bad practice to use the {set:} directive, and its use is
<em>highly</em> discouraged.  The reason is that it mixes the presentation and the content in one file.  Why not have
a single source file (devoid of {set:} directives), and then use Songbook files to produce the output.
This lets you have multiple versions of the song that rely on the same source.  (One version might transpose
itself while another uses a capo or prints the chord font extra large, for instance.)  When you correct a lyric
typo in the source, <em>all</em> of the Songbook versions will benefit.
</p>
</td></tr></table>
<h3><u>Directives NOT Supported</u></h3>
<p>
This list is not comprehensive, but these are some important ones that people familar with
ChordPro should be aware of:
</p>
<dl>
<dt>
{new_song} or {ns}
</dt>
<dd>
<p>
    I don't like the idea of storing more than one song in a file, so I don't do it.  Chordshop
    provides the SongBook File (.sbk) as a mechanism for collecting songs together.
</p>
</dd>
<dt>
{comment<sub>italic} and {comment</sub>box}
</dt>
<dd>
<p>
    Enough already.  {comment} will suffice.
</p>
</dd>
<dt>
{*font} and {*size}
</dt>
<dd>
<p>
    All of the font stuff is supported through configuration variables.  See the Chordshop
    User Guide's configuration section.  Also see the {set:} directive.
</p>
</dd>
<dt>
{grid}, {g}, {no_grid}, {ng}
</dt>
<dd>
<p>
    I would rather change this for an entire collection, so this
    should be handled somewhere other than the individual song file.
    e.g. the SongBook File or a command-line switch
    See the Chordshop
    User Guide's configuration section.  Also see the {set:} directive.
</p>
</dd>
<dt>
All Column and Page Breaks
</dt>
<dd>
<p>
    These will probably be supported in the future.  They are just not implemented yet.
</p>
</dd>
</dl>
<hr/>
<h2><u>Measures and Bars</u></h2>
<p>
The pipe character represents a measure bar.  The types of bars supported
include the normal bar "|" as well as repeat bars ":|", "|:" and ":|:".  To get
a repeat bracket above a measure, just append parathesis after the bar containing
the desired text.  For example: "|(1.)", "|(1.-3.)" or even "|(Tag)".  A bar <strong>must</strong>
be surrounded by whitespace. (The beginning and end of lines count as whitespace.)
A bar will not be recognized if it is touching a word (e.g. ":|word" or "word|").
</p>
<p>
You can also produce output from traditional ChordPro files that are not formatted with
bar delimiters.  If the input file has no bars in it, the display of measures is automatically
turned off, and the output will be similar to many other ChordPro-based programs.
</p>
<p></p>
<p></p>
<hr/><p><small>
Copyright 2004, Blake T. Garretson, All rights reserved.<br />
Last updated 07-Jul-2004 22:07:02 Eastern Standard Time
</small></p>
</body>
</html>
